feat(config): auto-detect supported config files in the working directory by AysajanE · Pull Request #901 · nodejs/doc-kit

AysajanE · 2026-07-12T22:22:09Z

Problem

doc-kit generate only loads configuration when --config-file is passed explicitly — loadConfigFile returns {} otherwise. As raised in #897, most config-driven tools also detect a conventional config file automatically, so a valid doc-kit.config.mjs sitting in the project root is silently ignored today. That is an easy footgun for anyone who assumes the file is picked up.

Change

In createRunConfiguration, when no --config-file is provided, auto-detect a doc-kit.config.mjs in the current working directory and load it through the existing loader. An explicit --config-file still takes precedence, and when no file is present the configuration falls back to empty — unchanged behavior. No new dependency; a tight happy path, as the issue suggests.
Add unit tests covering auto-detection, explicit-path precedence, and the no-file fallback.

Checks (Node 22)

node --test --experimental-test-module-mocks src/utils/configuration/__tests__/index.test.mjs — 17 passing, including the new cases.

Fixes #897

Disclosure: this change was prepared with AI assistance and reviewed by me before submitting.
I ran the check(s) above in a network-isolated container and published a signed, re-runnable
record of that run, verifiable via GitHub artifact attestation:
https://northset-oss.github.io/verification-pilot/. Contributor self-run, not a maintainer verification.

vercel · 2026-07-12T22:22:14Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 19, 2026 9:19pm

cursor · 2026-07-12T22:22:15Z

PR Summary

Low Risk
CLI configuration resolution only; explicit --config-file is unchanged and behavior falls back to {} when no file is found.

Overview
When --config-file is not passed, createRunConfiguration now uses cosmiconfig (doc-kit module name) to search the working directory for a config file and merge its config object. Explicit --config-file still goes through loadConfigFile / importFromURL and skips cosmiconfig.

Adds cosmiconfig as a runtime dependency and extends configuration unit tests for auto-discovery, explicit-path precedence, and the empty-config fallback when search finds nothing.

^{Reviewed by Cursor Bugbot for commit 4c8e448. Bugbot is set up for automated code reviews on this repo. Configure here.}

AugustinMauroy

adding blocker since feature isn't correctly covered.

thanks @AysajanE for you effort here

AysajanE · 2026-07-15T15:54:27Z

Thanks for the specific direction, @AugustinMauroy and @avivkeller. I have updated and rebased the branch to cover the full supported configuration-file set.

When --config-file is omitted, discovery now checks this exact priority order:

doc-kit.config.js
doc-kit.config.cjs
doc-kit.config.mjs
doc-kit.config.ts
doc-kit.config.cts
doc-kit.config.mts

The first existing file wins. An explicit configFile still bypasses discovery, JSON is not included because it is unsupported, and the no-file behavior remains unchanged.

Coverage now includes:

all six discovered filenames;
exact probe order and first-match priority;
explicit-path precedence;
no-file fallback;
native loading for TypeScript, CommonJS TypeScript, and ES module TypeScript configurations.

Local verification on current upstream main b9750dc:

focused configuration and loader tests: 34 passed
full test suite: 529 passed, 0 failed
lint: 0 errors; 2 pre-existing unrelated warnings
format check: passed
diff check: passed

I also checked the still-open dynamic-configuration PR #905. It touches the same configuration area but implements dynamic default values, so there is no semantic overlap with this file-discovery correction at present.

The updated head is 662687f. Could you please take another look when CI is ready?

avivkeller · 2026-07-17T22:05:44Z

I feel like a dep like cosmiconfig does this for us?

avivkeller · 2026-07-18T05:06:18Z

Didn't mean to close! Feel free to iterate based on my feedback

AysajanE · 2026-07-18T11:38:11Z

Thanks — that makes sense. I have reworked the revision locally to use cosmiconfig for discovery instead of maintaining the file-probing logic ourselves. The explorer is configured for the current working directory and the agreed six doc-kit.config.* names, in priority order; an explicit --config-file still bypasses discovery, and the existing loader remains responsible for JavaScript and TypeScript module loading.

Local verification is green: focused configuration tests 17/17, full suite 527/527, six-extension plus priority smoke check passed, lint has 0 errors (2 pre-existing unrelated warnings), and formatting passed. I have not updated the PR head yet.

avivkeller · 2026-07-18T15:03:05Z

Can you push those changes?

Signed-off-by: Aysajan Eziz <[email protected]>

AysajanE · 2026-07-19T09:56:24Z

Thanks — I’ve pushed the cosmiconfig revision in ed0755a.

Configuration discovery is now scoped to the current working directory and uses the agreed priority order for doc-kit.config.js, .cjs, .mjs, .ts, .cts, and .mts. An explicit --config-file still bypasses discovery.

Validation after the update:

focused configuration tests: 17/17 passed
full test suite: 527/527 passed
lint: 0 errors (2 pre-existing unrelated warnings)
formatting: passed
real-file smoke test: all six extensions and first-match priority passed

Please take another look when convenient.

codecov · 2026-07-19T10:59:43Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.17%. Comparing base (4534824) to head (ed0755a).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #901      +/-   ##
==========================================
- Coverage   86.17%   85.17%   -1.01%     
==========================================
  Files         188      192       +4     
  Lines       17146    17575     +429     
  Branches     1540     1565      +25     
==========================================
+ Hits        14776    14969     +193     
- Misses       2363     2599     +236     
  Partials        7        7

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

avivkeller · 2026-07-19T18:57:09Z

+        await cosmiconfig('doc-kit', {
+          searchPlaces: CONFIG_FILE_NAMES,
+          loaders: CONFIG_LOADERS,
+          searchStrategy: 'none',
+        }).search(process.cwd())


Why is this so complex?

Can we not just:

const explorer = cosmiconfig('doc-kit'); const result = await explorer.search();

You are right that search() already starts from process.cwd() and defaults to a non-traversing search, so the explicit working directory and searchStrategy are redundant.

The additional searchPlaces and loaders were preserving the six filenames requested in the earlier review: doc-kit.config.js, .cjs, .mjs, .ts, .cts, and .mts, with a defined priority. In particular, cosmiconfig defaults do not discover .cts or .mts, and using its defaults would also broaden discovery to package/rc/JSON/YAML conventions.

I can simplify this to cosmiconfig("doc-kit").search() if that earlier six-extension requirement is no longer desired. That would intentionally drop automatic .cts/.mts discovery and follow the standard cosmiconfig conventions instead, while explicit --config-file paths would remain unchanged. Could you confirm which behavior you prefer?

I'd prefer that you simplified this, as I had requested, regardless of MTS/TS support.

I'd also prefer to I spoke to a human :-)

Got it. I am reading every comment here as the real person Aysajan Eziz, as I am typing this manually.

Signed-off-by: Aysajan Eziz <[email protected]>

AysajanE requested a review from a team as a code owner July 12, 2026 22:22

vercel Bot deployed to Preview July 12, 2026 22:23 View deployment

avivkeller reviewed Jul 12, 2026

View reviewed changes

Comment thread .changeset/quiet-dingos-detect.md Outdated

AugustinMauroy reviewed Jul 13, 2026

View reviewed changes

Comment thread src/utils/configuration/index.mjs Outdated

AugustinMauroy requested changes Jul 13, 2026

View reviewed changes

AysajanE force-pushed the northset/M-012 branch from a0bdd2d to 662687f Compare July 15, 2026 15:54

AysajanE changed the title ~~feat(config): auto-detect doc-kit.config.mjs in the working directory~~ feat(config): auto-detect supported config files in the working directory Jul 15, 2026

vercel Bot deployed to Preview July 15, 2026 15:55 View deployment

fix: discover supported configuration files

bebe41e

AysajanE force-pushed the northset/M-012 branch from 662687f to bebe41e Compare July 17, 2026 11:05

vercel Bot deployed to Preview July 17, 2026 11:06 View deployment

avivkeller closed this Jul 17, 2026

avivkeller reopened this Jul 18, 2026

avivkeller mentioned this pull request Jul 18, 2026

feat: auto-detect default config file #913

Closed

4 tasks

fix: use cosmiconfig for config discovery

ed0755a

Signed-off-by: Aysajan Eziz <[email protected]>

vercel Bot deployed to Preview July 19, 2026 09:56 View deployment

avivkeller requested changes Jul 19, 2026

View reviewed changes

fix(config): simplify automatic config discovery

4c8e448

Signed-off-by: Aysajan Eziz <[email protected]>

vercel Bot deployed to Preview July 19, 2026 21:19 View deployment

avivkeller approved these changes Jul 19, 2026

View reviewed changes

Uh oh!

Conversation

AysajanE commented Jul 12, 2026

Problem

Change

Checks (Node 22)

Uh oh!

vercel Bot commented Jul 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented Jul 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

Uh oh!

Uh oh!

AugustinMauroy left a comment

Choose a reason for hiding this comment

Uh oh!

AysajanE commented Jul 15, 2026

Uh oh!

avivkeller commented Jul 17, 2026

Uh oh!

avivkeller commented Jul 18, 2026

Uh oh!

AysajanE commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

avivkeller commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AysajanE commented Jul 19, 2026

Uh oh!

codecov Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

avivkeller Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

AysajanE Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AysajanE Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel Bot commented Jul 12, 2026 •

edited

Loading

cursor Bot commented Jul 12, 2026 •

edited

Loading

AysajanE commented Jul 18, 2026 •

edited

Loading

avivkeller commented Jul 18, 2026 •

edited

Loading

codecov Bot commented Jul 19, 2026 •

edited

Loading

avivkeller Jul 19, 2026 •

edited

Loading